Skip to main content

API Reference

The Istari Digital Model Concept Protocol (MCP) Service provides structured access to system, resource, and job operations within the Istari platform.

It is organized into three categories:

  • System Tools: Manage systems, snapshots, and configurations.
  • Resource Tools: Handle models and artifacts.
  • Job Tools: Run automated analysis and processing.

System Tools​

Search for Systems​

Find existing systems by name, ID, or other criteria to discover what's available before working with them.

Use this to:

  • Find or list existing systems
  • Search systems by name or ID
  • Filter by archive status (Active/Archived)
  • Browse systems you've created

Input Parameters:

  • system_id (optional): Exact system IDs to match
  • name (optional): Case-insensitive substring search over system names
  • page (optional): Page number (≥1, used only when no local filters)
  • size (optional): Page size (1-100, used only when no local filters)
  • filter_by (optional): 'created_by_id' or '-created_by_id'
  • archive_status (optional): ["Active"], ["Archived"], or ["Active","Archived"]
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageSystem with matching systems and pagination metadata

Search System Files​

List all files tracked within a specific system's snapshot to explore system contents.

Use this to:

  • See what files are tracked within a system
  • Explore the contents of a system's snapshot
  • Filter by filename or file extension
  • Find specific files within a system

Input Parameters:

  • system_id (required): System ID whose snapshot revisions to list
  • snapshot_id (optional): Specific snapshot ID (defaults to baseline if omitted)
  • page (optional): Page number
  • size (optional): Page size (default 100)
  • name (optional): Filename substring filters
  • extension (optional): File extension filters (e.g., ['.xlsx', '.csv'])
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageSnapshotRevisionSearchItem with file revisions and metadata

Create a New System​

Create a new engineered system to organize related engineering files and configurations.

Use this to:

  • Create a new engineered system
  • Start organizing files for a new project or product
  • Set up a container for related engineering artifacts

Input Parameters:

  • name (required): System name
  • description (optional): Optional description for the new system

Returns: System object with ID, name, description, and metadata

Update a System​

Modify an existing system's metadata such as name or description.

Use this to:

  • Rename an existing system
  • Update or clarify a system's description
  • Modify system metadata without affecting its contents

Input Parameters:

  • system_id (required): Target system ID to update
  • name (optional): New name (only provided fields are updated)
  • description (optional): New description (only provided fields are updated)

Returns: Updated System object with modified metadata

List System Snapshots​

View snapshots/versions of systems or configurations to track version history.

Use this to:

  • See snapshots/versions of a system or configuration
  • Browse version history
  • Find specific snapshots by tag (like "baseline")
  • Track changes over time

Input Parameters:

  • system_id (optional): Filter snapshots by system ID
  • configuration_id (optional): Filter snapshots by configuration ID
  • tag (optional): Filter by snapshot tag (e.g., 'baseline')
  • page (optional): Page number
  • size (optional): Page size
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageSnapshot with snapshot list and pagination metadata

Create a System Snapshot​

Generate a snapshot/checkpoint of a system configuration to preserve a point-in-time state.

Use this to:

  • Create a snapshot/checkpoint of a system configuration
  • Preserve a version for future reference
  • Establish a baseline or milestone

Input Parameters:

  • configuration_id (required): Configuration ID to snapshot

Returns: ResponseCreateSnapshot with snapshot creation details

Add Files to System​

Create a new system configuration that tracks specified existing files (sets them to LATEST version).

Use this to:

  • Attach existing files to a system
  • Track files within a system configuration
  • Build a system from previously uploaded files
  • Create a new configuration with selected files

Input Parameters:

  • system_id (required): System ID to attach files to
  • file_ids (required): List of existing file IDs to track (set to LATEST)
  • configuration_name (optional): Name for the new configuration (defaults to 'Default Configuration')

Returns: SystemConfiguration object with tracked files and metadata

Resource Tools​

Search Resources​

Search for engineering models, artifacts, comments, or jobs across the Istari registry with flexible filtering options.

Use this to:

  • Find or list engineering models, artifacts, comments, or jobs
  • Search by filename, description, version, or metadata
  • Filter by file type, creation date, or status

Input Parameters:

  • page (optional): Page number (≥1)
  • size (optional): Page size (1-100)
  • resource_id (optional): Resource IDs to match
  • type_name (optional): ["model"], ["artifact"], ["comment"], ["job"] or combinations
  • file_name (optional): File name substring filters
  • description (optional): Description substring filters
  • version_name (optional): Version name substring filters
  • external_identifier (optional): External identifier filters
  • display_name (optional): Display name substring filters
  • mime_type (optional): MIME type filters (e.g., 'text/csv')
  • file_size (optional): Exact file sizes in bytes
  • created_timestamp (optional): Creation timestamps (ISO-8601)
  • updated_timestamp (optional): Update timestamps (ISO-8601)
  • created_by_id (optional): Creator user ID filters
  • updated_by_id (optional): Last updater user ID filters
  • archive_status (optional): ["Active"], ["Archived"], or both
  • sort (optional): "created" (ascending) or "-created" (descending)

Returns: PageResourceSearchItem with matching resources and pagination metadata

Download File Contents​

Retrieve the raw file bytes for a resource using its File ID for local processing.

Use this to:

  • Download or access actual file contents
  • Get raw bytes of a file for processing or analysis
  • Retrieve files for local use or downstream processing

Input Parameters:

  • file_id (required): The ID of the resource file to retrieve

Returns: Raw binary file contents (bytes) - works with CSV, Excel, images, ZIP, JSON, etc.

Get Resource by File ID​

Retrieve the model or artifact metadata associated with a given File ID.

Use this to:

  • Get metadata about a resource when you only have a file ID
  • Understand what type of resource a file belongs to
  • Trace a file back to its full resource context

Input Parameters:

  • file_id (required): The ID of the resource file (Model.file.id or Artifact.file.id)

Returns: Model or Artifact object with full metadata, or None if not associated

Job Tools​

Run Extraction​

Execute the Istari extraction function on a model to generate artifacts and extract structured data.

Use this to:

  • Extract data, metadata, or information from CAD models or engineering files
  • Generate artifacts from models (drawings, reports, analysis data)
  • Process, analyze, or extract information from engineering files
  • Get structured information from CAD files

Supported File Types:

  • CAD files: .CATPart (CATIA), .prt (Creo)
  • Documents: .pdf, .xlsx (Excel)

Input Parameters:

  • model_id (required): Model ID to run the @istari:extract function on

Returns: Updated Model object with:

  • Generated artifacts list
  • Job execution details
  • Processing metadata
  • Updated model status

Run Update Parameters​

Execute the Istari update parameters function on a model to modify CAD parameters or design variables.

Use this to:

  • Modify parameters, dimensions, or variables in CAD models
  • Update design values or configuration settings
  • Change, update, modify, or set parameters in engineering models
  • Apply new parameter values to regenerate models

Supported File Types:

  • CAD files: .CATPart (CATIA), .prt (Creo)

Input Parameters:

  • model_id (required): Model ID to run the @istari:update_parameters function on
  • parameters (required): Dictionary of parameter names and string values to update

Returns: Updated Model object with:

  • Generated artifact (The updated CAD file)